Skip to content

Add the Security section to the documentation - #88

Merged
alexander-yevsyukov merged 5 commits into
masterfrom
security-section
Oct 1, 2026
Merged

alexander-yevsyukov merged 5 commits into
masterfrom
security-section

Conversation

@alexander-yevsyukov

Copy link
Copy Markdown
Contributor

Adds Documentation → Security with three pages, per .agents/tasks/security-docs-tasks.md (part 1):

Page URL Content
Security policy /docs/security/policy/ SECURITY.md of SpineEventEngine/.github, fetched at build time
Verifying artifacts /docs/security/verifying-artifacts/ New: checking SLSA build provenance with gh attestation verify
CVD Policy /docs/security/cvd-policy/ Moved verbatim from spine.io's /cvd-policy/

What changed

  • remote-markdown shortcode (docs/layouts/_shortcodes/): fetches a Markdown file with resources.GetRemote and renders it into the page, headings and TOC included. The org-wide SECURITY.md stays the only source of the policy text; there is no copy to drift.
    • A failed fetch (network error or HTTP 404) fails the build, so the page never ships empty. Under hugo server it's a warning plus a link to the file, so offline authoring still works.
    • It's a shortcode in a real policy.md, not a content adapter: adapter pages have no .File, and the site-commons sidenav finds the current section from .File.Path.
  • Verifying artifacts page: what is attested, what a passing check does and doesn't prove, prerequisites, the command with a worked example, why each flag is there, choosing the branch, an "If the check fails" section, and optional --signer-digest pinning. Adapted for consumers from the config README; maintainer-only details are left out.
  • CVD Policy page: the body is byte-identical to spine.io's; only the front matter changed (docs headline, a description, same lastmod, has_numbered_headings kept).
  • Navigation: Security comes last, after the Validation guides. The theme always lists the main sidenav before module sidenavs, so Security has its own docs/data/docs/security/sidenav.yml, placed by moduleOrder in docs/hugo.toml.
  • Preview config: [caches.getresource] maxAge = '1h'. Hugo's default never expires fetched files, and the check-links workflow restores the Hugo cache between runs, so it would otherwise keep serving the first SECURITY.md forever.
  • date shortcode for the preview: the moved page uses it. spine.io has its own with the same output, which takes precedence there.

Other commits on this branch

  • Update config and Select CodeMatters (c) profile: the config submodule update and the IntelliJ copyright profile switch.
  • Update copyright headers: a repo-wide refresh to the CodeMatters notice (build scripts, samples, one JS file).
  • Add task doc for the Security section: the task document, updated in the last commit with the decisions and the merge order.

Merge order: spine.io follow-up

The redirect lives in spine.io, which serves /cvd-policy/ today. Its branch security-section (not pushed yet) does the following:

  • deletes the old page and adds a static redirect /cvd-policy/ → /docs/security/cvd-policy/;
  • updates the footer link and the Policy: line of security.txt (also fixes its invalid Expires: timestamp);
  • makes the docs layout honour has_numbered_headings and fixes the numbered-TOC CSS;
  • adds the same cache expiry;
  • adds a workflow_dispatch deploy trigger, limited to master, to publish SECURITY.md changes.

Merge this PR first. The spine.io PR must then add a bump of the documentation module pin. Without it, /cvd-policy/ would redirect to a page that doesn't exist yet.

Parts 2 (.github SECURITY.md pointer) and 3 (config README) wait until the pages are live.

Verification

  • hugo (production) build of the preview: no errors or warnings, 95 pages.
  • spine.io built against this branch via HUGO_MODULE_REPLACEMENTS: pages, sidenav order and expansion, prev/next chain, redirect (with and without the trailing slash), footer, and numbered headings and TOC all checked in a browser.
  • Shortcode failure paths tested in a scratch site: HTTP 404 and an unreachable host fail the build; hugo server warns and shows the fallback.
  • Link check (lychee, CI configuration): 0 broken links.
  • A review-docs pass; its findings were applied.

Note for reviewers

The Security policy page renders SECURITY.md from master of SpineEventEngine/.github, and the site renders raw HTML in Markdown. That branch needs a ruleset, which is listed in the task document's preconditions.

🤖 Generated with Claude Code

alexander-yevsyukov and others added 5 commits September 30, 2026 19:15
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Add Documentation > Security with three pages:

- Security policy: `SECURITY.md` of `SpineEventEngine/.github`, fetched
  when the site is built by the new `remote-markdown` shortcode, so the
  organization-wide file stays the only source of the text.
- Verifying artifacts: how to check the SLSA build provenance of our
  Maven artifacts with `gh attestation verify`, adapted for consumers
  from the `config` README.
- CVD Policy: moved verbatim from spine.io, which redirects
  `/cvd-policy/` to it in a follow-up change there.

The section comes last in the navigation, after the Validation guides,
through a sidenav of its own that `moduleOrder` places after the
modules. The preview gets a `date` shortcode for the moved page, and
fetched files expire after an hour, so a Hugo cache restored by CI does
not keep serving an old `SECURITY.md`.

The task document records the decisions and the merge order.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Sep 30, 2026 •

Copy link
Copy Markdown

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-09-30T20:21:46.034579Z 1d7c3e1 PR opened
ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

@alexander-yevsyukov
alexander-yevsyukov merged commit d144059 into master Oct 1, 2026
4 checks passed
@alexander-yevsyukov
alexander-yevsyukov deleted the security-section branch October 1, 2026 08:38
@github-project-automation github-project-automation Bot moved this from In Review to ✅ Done in v2.0 Oct 1, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

Archived in project

Development

Successfully merging this pull request may close these issues.

2 participants